.! Proff user's manual .! Feb. 1984 by Ozan S. Yigit .! .! Edited by Steven Tress and Terry Lim .! vers. 1.0 .! .! ----------- macros ---------- .! sect - produce a bold section header and .! enter a contents line. First parameter .! is indent level for contents line. .define sect .sp .cl $1 $2 $3 $4 $5 $6 $7 .bd $2 $3 $4 $5 $6 $7 .en .! ----------------------------- .define note .sp .ce NOTE .sp .fi .in +5 .rm -5 .en .define endnote .sp .nf .in -5 .rm +5 .en .! ----------------------------- .! Macros to create a point-form lists. .! Note the use of number registers within .! the macros. See section 5. .! .define list .nr a $1 .in +$1 .en .define item .sp .ti -@na $1 .en .define nolist .in -@na .sp .en .! ----------------------------- .ce 100 .st 8 PROFF User's Guide .sp Version 1.0 .ce 0 .nf .in +25 .sp 15 *** ******* *** ********* ** ** ** ** ********* ******* ** ** ** ****** **** .in -25 .fi .ce 100 .st -8 Ozan S. Yigit & Steven Tress March 1984 .ce 0 .bp 1 .he /1.0/Proff User's Guide/#/ .ap .fi .ju .sect 0 1.0 Introduction This manual describes PROFF, a formatter based on the FORMAT utility presented in .ul Software Tools. PROFF was produced to provide a powerful formatter that can be used under a variety of microcomputers, thus providing a consistent formatting tool across environments. PROFF can be used to format memos, reports, form letters and documents such as this manual. It can also be configured to mimic other formatting systems of similar nature. This document itself was produced with PROFF, using most of its advanced features. PROFF took care of such things as auto-paragraphing and the production of the Table of Contents as the manual was being formatted. PROFF was developed under a Digital Equipment Corporation Rainbow 100, using Mark Williams C Compiler for portability reasons. PROFF is available under VAX/VMS operating system. PROFF implementations for IBM PC and APPLE ][ microcomputers are also underway. .st -14 Rainbow, VAX/VMS are trademarks of Digital Equipment Corporation. .br Mark Williams C Compiler is a trademark of Mark Williams Company. .br IBM is a registered trademark of International Business Machines Inc. .br APPLE is a trademark of Apple Computer Inc. .br UNIX is a trademark of Bell Laboratories. .bp .cl .sect 0 2.0 General Description .cl .sect 1 2.1 The Input The text that is to be formatted by PROFF is typed into an input file using any text editor. This file contains the text to be formatted as well as PROFF commands. Each line in the input file is either a command line or a text line. A command line is a line that begins with a period ("."). All other lines are text lines. The command lines are not printed - they tell PROFF how you want it to format the text that follows. Appendix A summarizes all of the PROFF commands for a quick reference. .sect 2 2.1.1 Text Text can be entered into the input file in any format. PROFF removes all extra blanks and tabs between words when operating in fill mode. This means you do not have to worry about how many words you put on a line, and you can break lines wherever it is convenient to your typing. Note however, that you cannot break a word between two lines. Blanks and tabs at the beginning of a line are not removed. This is useful for producing special tables and performing special types of indentation. Thus, normal text lines should not have any leading tabs or blanks. .sect 2 2.1.2 Commands A command is a line that starts with a period. Immediately following the period is a command name. Some commands accept a numeric quantity or a character string parameter, which must be separated from the command name by a space or a comma. For example, an indent command might appear as follows: .save .in +5 .nf .nj .sp | |It is to do nothing that the elect exists. |.in 5 |- Oscar Wilde | .restore Assuming that the left margin was at column 1, PROFF would produce the following: .save .in +5 .nf .nj .sp .need 4 | |It is to do nothing that the elect exists. | - Oscar Wilde | .restore .sp (In the examples above, as in those following, the vertical line indicates the left edge of input or the left edge of the printed page). The number following the command may be preceeded by a "+" or "-" sign. This plus or minus sign indicates an addition or subtraction of the number to or from the current value for the command. for example, the text: .sp .save .in +5 .nf .nj .need 11 | |Nothing to do but work, |.in +3 |Nothing to eat but food, |.in -3 |Nothing to wear but clothes |.in +3 |To keep one from going nude. |.in +7 |-Benjamin King | .in -5 .sp will produce as output: .sp .in +5 .need 6 | |Nothing to do but work, | Nothing to eat but food, |Nothing to wear but clothes | To keep one from going nude. | -Benjamin King | .restore If a number is not supplied with a command that requires a number, PROFF will use a default value. The defaults for each command are summarized in Appendix A. .cl .sect 1 2.2 The Output The main functions performed by PROFF are .ul filling and .ul justifying. A line is filled by packing as many words onto it as will fit. The line is justified by spacing words evenly between the left and right margins. When PROFF starts, it assumes that the text is to be filled and justified. Of course, when fill and justify are not needed (as in the case of a letter or a table), there are commands to turn these features off, and back on again, as necessary. When PROFF is in fill mode, it normally strips out extra spaces and tabs between words. Many PROFF commands cause a .ul break to occur in the output. This means that the line currently being filled is immediately output. Any following text goes into a new output line. .cl .sect 1 2.3 Executing PROFF Once a text file is ready for formatting, PROFF is started by typing the program name, various options, name of the input file and the name of the output file. For example the command .sp .in +5 A> proff -po5 proffman.prf proff.man .sp .in -5 would produce this document as proff.man, from an input file proffman.prf, shifted right by 5 spaces. (The symbol "A>" is CP/M system prompt). .cl .sect 1 2.4 Bibliographic Notes PROFF wa produced by re-writing the Software Tools Formatter FORMAT. Some of the ideas are from Freshwater Institute RUNOFF, NROFF, University of Waterloo SCRIPT and other formatters of similar nature. The underlying ideas of the mentioned above formatters may be found in .ul Software Tools by B.W. Kernighan and P.J. Plauger. 1976. (Addison-Wesley, Reading, Mass.). .cl .sect 1 2.5 References and Readings .nf .nap .sp Brian W. Kernighan and P. J. Plauger, .ul Software Tools Addison-Wesley (1976) .sp R. Furuta, J. Scofield and A. Shaw, .ul Document Formatting Systems: .ul Survey, Concepts, and issues ACM Computing Surveys, Sept. 1982, Pp. 417 .sp Mark Stuart Brader, .ul An Incremental Text Formatter Department of Computer Science University of Waterloo, CS-81-12 .bp .fi .ap .cl .sect 0 3.0 Command Descriptions This section describes PROFF commands. Commands specify how the program is to process the text lines in the input file. Lines in the input file that begin with a period (or the control character selected by the user) immediately followed by a command name are commands. Any line that begins with a period and followed by a _# or _! is a comment line and is ignored by PROFF - this allows you to put information in the file that will be neither processed nor output by PROFF. As described earlier, some of the commands can be followed by "parameters". Parameters are used in executing a command; for example, in the command ".sp 3", the parameter "3" tells the formatter to insert 3 blank lines into the document. The following conventions are used in describing the parameters: .sp .in +5 .ti -2 o Parameters surrounded by square brackets are optional. If not supplied, PROFF assumes a default value. .br (e.g. .sp [n]) .sp .ti -2 o Parameters surrounded by angle brackets are mandatory. PROFF will display a fatal error message if the parameter is absent. (e.g. .set ) .sp .ti -2 o Parameters surrounded by squiggly brackets are to be typed exactly as indicated. (e.g. .pn {roman}) .sp .ti -2 o A bar character seperating the parameters within brackets indicate an alternative. (e.g. .st [+|-][n] means both .st [+n] and .st [-n]) .in -5 In describing the commands, the command is typed exacty as accepted by PROFF with the associated control character default ("."). If more than one form of the command is accepted by PROFF, the command names are separated with a bar indicating an alternative. .bp .cl .sect 1 3.1 Filling and Justifying .nap .in +5 .! .! define a simple macro for generating the headers. .! note that the second "$" within macro is for .! variable expansion. Initially, the variable name .! is passed into the macro WITHOUT any expension. .! we also use the new control character within macro. .! .define comm \sp \cl 2 $$1 \ti -5 $$1 \sp .en .! change the control character from period (".") to a backslash ("\") .! to avoid the interpretation of the command headers .! .cchar \ \! \! Variable creation \! We use variables to avoid re-typing of multiple options over \! and over again. These variable names will be reused in the \! appendix to produce a quick referance \! \set FILL ".fi | .f | .fill" \comm FILL The fill command causes a line to be filled with as many words as the right margin allows. For this purpose, all extra blanks and tabs are removed between words. Each word is separated with a single blank. PROFF automatically assumes fill mode during the startup. \set NOFILL ".nf | .nofill" \comm NOFILL No fill discontinues the filling of the text. PROFF simply copies the text to the output. This command may be used to pass tables and other text unaltered through the formatter. \set JUST ".ju | .j | .justify" \comm JUST Justify causes the words on a line to be evenly spaced between the left and the right margins. Note that lines can be justified only if lines are also being filled. PROFF automatically assumes justify mode during the startup. \set NOJUST ".nj | .nojustify" \comm NOJUST No justify discontinues the text justification. \in -5 \cchar . .bp .cl .sect 1 3.2 Text Formatting .in +5 .cchar \ \set BREAK ".br | .break" \comm BREAK Break causes a break: the current line is printed without justification, and the next word is placed at the beginning of a new line. Note that many PROFF commands cause an implicit break. \set INDENT ".in | .lm | .leftmargin [+|-][n]" \comm INDENT Indent causes a break and indents the following lines [n] spaces to the right of the left margin. [n] can be negative to allow beginning a line to the left of the left margin, however, a line cannot begin to the left of column 0. If a plus or minus sign is used with n, then [n] is added or subtracted to or from the current value. \set TINDENT ".ti | .i | .left [+|-][n]" \comm TINDENT Temporary indent is identical to the indent command except that it applies only to the next line of printed text. Thus, the command ".ti +5" would cause the next line to be printed 5 spaces to the right of those that follow. \set SPACETO ".st | .spaceto [-][n]" \comm SPACETO Spaceto allows spacing to line [n] from the top of the current page. If a negative [n] is specified, than spacing is performed to line [n] from the bottom of the page (excluding the footer lines). Thus, footnotes can be set at a fixed distance from the bottom of the page by a command such as ".st -5". \set SPACE ".sp | .s | .skip [n]" \comm SPACE Space causes a break and skips [n] lines, except at the top of a page. The space command is dependent on the setting of line spacing. \set CENTER ".ce | .center [n | on | off]" \comm CENTER Center causes the next [n] lines of text to be centered between the left and right margins. Centering may be started with "on" and terminated with "off", in which case all input lines between these commands will be centered. \set UNDLINE ".ul | .underline [n | on | off]" \comm UNDLINE Underline command causes the text on the next [n] input lines to be underlined when printed. If [n] is omitted, only the next line is underlined. This command does not cause a break, so words in filled text may be underlined by: \sp \save \cchar . .in +5 .nf .need 11 .sp | |The "Pay-off" Theory: Only |.ul |losers |believe in luck, horses, horoscopes |and |.ul |lotteries. | .in -5 .sp to get .in +5 .sp .fi | .br |The "Pay-off" Theory: Only .ul losers believe in .br |luck, horses, horoscopes and .ul lotteries. .br | .sp .restore Underlining may be started with "on" and terminated with "off", similar to the centering command. \set CUNDLINE ".ul | .underline [all | words]" \comm CUNDLINE This version of the underline command is used to set the mode of underlining: \sp \nap \in +5 \nf all - underline across all characters, including spaces. \br words - underline words only \fi \sp \in -5 \ap \set BOLD ".bd | .bold [n | on | off]" \comm BOLD The bold command causes the text on the next [n] input lines to be highlighted by overstriking. If [n] is omitted, only the next line is highlighted. Bolding may be started with "on" and terminated with "off" as in the case of the center and underline commands. \set DBO ".db | .dbo | .disablebolding" \comm DBO Turns the bolding off, all bolding commands are ignored. This feature is useful for rough drafts. \set EBO ".eb | .ebo | .enablebolding" \comm EBO Turns the bolding feature back on. Bolding is turned on during the PROFF startup. \in -5 \cchar . .bp .cl .sect 1 3.3 Page Formatting .in +5 .cchar \ \set LS ".ls | .spc | .spacing [n]" \comm LS Line spacing is the command to set line spacing. Set n to 1 for single spacing, 2 for double spacing etc. \set BP ".bp | .pg | .page [n]" \comm BP The begin page command causes a break, ends the current page, outputs footers if required and begins a new page. If [n] is present, the page number is set to [n]. The default action is to number the pages incrementally. \set PN ".pn | .pagenumber {roman} | {arabic}" \comm PN Page number command defines the format of the page number. Uppercase roman numerals may be obtained with "roman" keyword. To convert the page numbers back to normal, "arabic" is specified. PROFF uses arabic numerals as a default. \set NPA ".np | .nopaging" \comm NPA No paging disables the pagination. When PROFF is in no paging mode, "begin page" (.bp) and "page length" (.pl) commands are ignored. This mode of operation is especially useful for using the proff output with the multi-column formatter (MC). \set PA ".pa | .paging" \comm PA Paging enables normal page generation. This command starts a new page and restores the page length to the value previous to the ".np" command. \set NE ".ne | .need | .tp | .testpage [n]" \comm NE Test page checks to see whether at least [n] lines remain in the current page. If less than this number of lines remain, printing will resume at the top of a new page. If [n] is missing, it is assumed to be zero. \set HE ".he | .header " \comm HE Header sets the text to be printed on top of each page. is divided into sections which are to be left justified, centered and right justified. To divide into these three parts, the first character is assumed to be a separator. (e.g. /left/center/right/) But any non-alphanumeric character may also be used. The characters "#" and "%" are replaced with the current page number and day/time in the header. \set FO ".fo | .footer " \comm FO Footer is identical to header except that it sets the text to be printed at the bottom of each page. \set OHE ".oh " \comm OHE The odd header command sets the header for odd pages only. \set EHE ".eh " \comm EHE The even header command sets the header for even pages only. \set OFO ".of " \comm OFO The odd footer command sets the footer for odd pages only. \set EFO ".ef " \comm EFO The even footer command sets the footer for even pages only. \in -5 \cchar . .bp .cl .sect 1 3.4 Page Layout .ap These commands are used to specify where on the page you want the formatted text to be placed. The general layout of a page is as follows: .nap .need 30 .nf page offset (.po) | | | V | +----+-------------------------------------+----+ -+ | | top margin (m1) includes header | | | +----+-------------------------------------+----+ | | | top margin 2 (m2) | | | +----+-------------------------------------+----+ | | | . | | P | |<-- indent (.in) . | | A | | . | | G | | T | | E | | E | | | | X | | L | | T | | E | | . | | N | | right margin (.rm) -->| | G | | . | | T | | . | | H | | . | | | +----+-------------------------------------+----+ | | | bottom margin 3 (m3) | | | +----+-------------------------------------+----+ | | | bottom margin (m4) includes footer | | | +----+-------------------------------------+----+ -+ | | | | .fi .in +5 .cchar \ \set PO ".po | .offset [+|-][n]" \comm PO The page offset command moves the entire page to the right or left depending on the specified value. All indentation is according to the page offset. PROFF assumes a page offset of 0 during the startup. If [n] is specified with a plus or minus, it will be added or subtracted from the current value. \set RM ".rm | .rightmargin [+|-][n]" \comm RM Right Margin sets the position of the last printable character from the left edge of the page to [n]. Default value for right margin is 65. A plus or minus value will be added or subtracted from the current value. If [n] is not specified, right margin is set to the default value. \set PL ".pl | .ps | .pagesize [n]" \comm PL Page length is used to set the number of lines that are to be printed on a page including the header and footer lines. After [n] lines are printed, the paper will advance to the top of next page. The default page length is 66 lines (11 inches for 6 lines/inch). This command is disabled if nopaging is set. \set M1 ".m1 [n]" \comm M1 Margin 1 sets the number of lines (including the header) which will be left at the top of the page to [n]. The default setting is 3. If [n] is omitted, is set to the default. \set M2 ".m2 [n]" \comm M2 Margin 2 sets the number of blank lines between the header and the first line of text. The default setting is 2. \set M3 ".m3 [n]" \comm M3 Margin 3 sets the number of blank lines between the footer and the last line of text. The default setting is 2. \set M4 ".m4 [n]" \comm M4 Margin 4 sets the number of lines (including the footer) which will be left at the bottom of the page to [n]. The default setting is 3. \in -5 \cchar . .bp .cl .ap .sect 1 3.5 Table of Contents This section describes the the commands that are used to generate a table of contents. Basically, a contents line command is used in every place in the document where an entry is needed in the table of contents. PROFF stores the text and the page number when it encounters this command. After the the body of the document is processed, a print contents command dumps the contents table. The contents should be dumped in a new page, with nofill. Page numbering should be disabled if the table of contents is to be used in front of the document. .sp .in +5 .ap .cchar \ \set CL ".cl | .contline [ ]" \comm CL Contents line specifies a line of to be entered into the table of contents. specifies the level at which the item is to be printed in the table. When the table is printed, each level of entry will be indented by specific number of spaces. appears in the output exactly as it appears in the contents line command, except that leading blanks are removed. If no options specified in the contents line, a blank is inserted during the table output. \set PC ".pc | .printcont [n]" \comm PC Print Contents causes the currently accumulated table of contents to be printed. If [n] is specified, it is used as the indent value for each level. If [n] is not specified, it is defaulted to 3. A contents line at level 0 is as wide as rightmargin-indent. The outlook of the table of contents may be changed by altering the right margin and indent values. A typical table of contents may be produced as follows: \in +5 \nf \sp |.page |.he //// |.fo //// |.nofill |.sp |.center |Table of Contents |.sp |.printcont \in -5 \fi \sp The following example illustrates the generation of a table of contents. Note that only one table of contents is active for a PROFF session. \need 40 \sp \in +5 \nf \nap .cl .cl 0 A. Introduction Introduction text . .cl .cl 0 B. Methods Methods text . .cl 1 a) Sampling Procedures Sampling text . .cl 1 b) Laboratory Procedures Laboratory text . .cl .cl 0 C. Results Results text . . .pg .nf .he //// .fo //// .ce Table of Contents .sp .pc \sp \in -5 These commands will produce the following table: \sp \in +5 Table of Contents A. Introduction............................... 1 B. Methods.................................... 3 a) Sampling Procedures..................... 3 b) Laboratory Procedures................... 4 C. Results.................................... 5 \sp \in -5 \fi Macros may be defined as described in the following sections to help the generation of the table of contents. \cchar . .in -5 .bp .cl .ap .sect 1 3.6 Miscellaneous This section describes miscellaneous commands that radically increase the formatting powers of PROFF. With the assistance of variables, PROFF can generate form letters and documents with dynamic parts. The ability to save and restore formatter context eliminates the need to remember the exact settings of the formatter across the document. .in +5 .cchar \ \set VSET ".vs | .set [definition]" \comm VSET Set variable defines a variable to be later used in the document. If the definition part is left out, PROFF uses the variable name as a prompt and allows the user to define the variable interactively. Variable names cannot start with a numeric character, and may only contain alphanumeric characters. The definition of a variable may not contain any blanks, unless they are surrounded by double-quotes. To get a double quote within a a quoted definition, two double-quotes are used. Once the variable is defined, it can be used anywhere in the document, including the command line itself. A variable substitution is invoked by a dollar sign (_$). (A literal _$ is inserted into text using ___$). A variable name must be delimited by a non-alphanumeric character within the text. If the contents of the variable is to be appended to other alphanumeric characters, it must be surrounded by wiggly braces ("{" and "}"). The following is an example of variable usage: \need 12 \sp \nf |.nf |.vs v1 Murphy |_${v1}'s first law: | Nothing is as easy as it looks. |_${v1}'s second law: | Everything takes longer than you think. |Charley's observation: | Computers were invented by _$v1. | \sp Produces the following: \sp \need 8 | |Murphy's first law: | Nothing is as easy as it looks. |Murphy's second law: | Everything takes longer than you think. |Charley's observation: | Computers were invented by Murphy. | \sp \fi \set VGET ".vg | .get " \comm VGET Get variable is the interactive version of variable definition. In this variant, a prompt string is used to obtain the value of the variable, which is typed at the user's terminal. If the prompt string is to contain blanks, tabs etc., it must be enclosed in double quotes. No quotes are necessary for input text. \set VRG ".nr [+|-][n]" \comm VRG Number register is used to define registers that contain numeric values. There are 26 number registers, named a-z. The command ".nr x n" sets the number register "x" to value n; ".nr x +n" increments the number register by n; ".nr x -n" decrements the number register by n. The value of the number register x is placed in the text by the appearance of _@nx. A literal _@ may be inserted using ___@. Number registers may be used on command lines and anywhere in the text. \set CCHAR ".cc | .cchar [char]" \comm CCHAR Control Character sets the character that distinguishes PROFF commands from text to be formatted. As a default, control character is set to (".") period. This character may be changed to something other than a period, either to mimic other formatters or to disallow interpretation of lines beginning with a period. (This document makes heavy use of the .cc command). \set ECHAR ".ec | .echar [char]" \comm ECHAR Escape Character sets the character that disallows the interpretation of spacial characters such as _@ and _$. PROFF uses an underline ("__") character as a default. \set SOU ".so | .source | .include | .require [filename]" \comm SOU The source (include) command allows external files to be inserted into the input file during the formatting. Using this feature, tables, graphs and other documents generated outside PROFF may be included into the document being formatted. This feature is also very useful in including a common set of macros during formatting. Include files may be nested inside other include files. Currently, PROFF only allows a nested include files level of 8. Filename may be enclosed in quotes. \set SAVE ".sv | .save" \comm SAVE The save command allows the saving of the current formatter context on a pushdown stack. The saved context of the formatter segment (FSECT) includes the following values and flags: \need 14 \sp \nf \nap values flags on | off ------ ----- indent (.in) fill (.fi | .nf) right margin (.rm) justify (.ju | .nj) offset (.po) paging (.pa | .np) line spacing (.ls) number type (.pn) page length (.pl) bolding (.eb | .db) margin values (.m1) autoparagraph (.ap | .na) (.m2) (.m3) (.m4) control char (.cc) escape char (.ec) \sp \ap \fi \set RST ".rs | .restore" \comm RST The restore command pops the context stack and restores the values and flags as defined above. \set LEX ".lx | .lex [equate]" \comm LEX The lexical modification command is essentially a permanent replacement of a given command. This command is used for changing the command names without resorting to the macro facility. Lex permanently removes the old command name from command tables and replaces it with the new definition. If the equate is not specified, the command becomes undefined and is no longer recognised by PROFF. The command equate should not contain non-alphanumeric characters. \set APR ".ap | .autoparagraph" \comm APR The autoparagraph command turns on the automatic paragraphing feature. If auto-paragraphing is on, every line that starts with a \ul blank or a \ul tab character starts a new paragraph. A new line is generated (.sp) and the beginning of the paragraph is indented by five spaces. Autoparagraphing is the equivalent of the following commands: \in +5 \nf | |textextextextext |.sp |.ti +5 |textextextextext | \in -5 \fi \set NAP ".na | nap | .noautoparagraph" \comm NAP No Autoparagraph command disables auto-paragraphing. \set WRT ".wr | .write " \comm WRT Write is a special output command, only to be used to configure printers and other output devices with escape sequences. This command outputs the associated string as it is encountered, without going through the normal output routines of the formatter. Currently, the output string may contain control characters specified as "^", decimal numbers within the range of 1-255, and other characters. Blanks within the string are skipped. Any portion of the string enclosed with double quotes is output as is. To output a double quote, two double quotes must be used within the quoted string. Following is a typical string to set a Digital La-100 printer to letter quality print mode: \sp \nf \in +5 | |.wr ^["[2z" | \sp \fi \in -5 In the control string, "^[" is the ASCII equivalent of the Escape (esc) character. Following mapping table is used to convert characters starting with a caret to their binary equivalents: ("|" indicates an alternative) \nf \nap \sp \in +5 Control chr Dec. Oct. Hex. ----------- ---- ---- ---- ^a | ^A (soh) 1 01 01 ^b | ^B (stx) 2 02 02 ^c | ^C (etx) 3 03 03 ^d | ^D (eot) 4 04 04 ^e | ^E (enq) 5 05 05 ^f | ^F (ack) 6 06 06 ^g | ^G (bel) 7 07 07 ^h | ^H (bs) 8 10 08 ^i | ^I (ht) 9 11 09 ^j | ^J (nl) 10 12 0A ^k | ^K (vt) 11 13 0B ^l | ^L (np) 12 14 0C ^m | ^M (cr) 13 15 0D ^n | ^N (so) 14 16 0E ^o | ^O (si) 15 17 0F ^p | ^P (dle) 16 20 10 ^q | ^Q (dc1) 17 21 11 ^r | ^R (dc2) 18 22 12 ^s | ^S (dc3) 19 23 13 ^t | ^T (dc4) 20 24 14 ^u | ^U (nak) 21 25 15 ^v | ^V (syn) 22 26 16 ^w | ^W (etb) 23 27 17 ^x | ^X (can) 24 30 18 ^y | ^Y (em) 25 31 19 ^z | ^Z (sub) 26 32 1A ^[ (esc) 27 33 1B ^\ (fs) 28 34 1C ^] (gs) 29 35 1D ^^ (rs) 30 36 1E ^__ (us) 31 37 1F \sp \in -5 \ap \fi \cchar . .in -5 .bp .cl .sect 1 3.7 Defining New Commands (Macros) In document formatting, it is common to repeat a series of commands at several places in the document. PROFF allows you to define a new command that will replace these repeated commands. This not only saves typing but ensures that .ul exactly the same sequence of commands are applied throughout the document. A new command that you define is formally called a .ul macro. To define a macro, you must use the define macro (.de | .define) and end macro (.en) commands. .in +5 .cchar \ \set DEF ".de | .define " \comm DEF Define is used to define a to which a series of commands to be assigned. This definition line is followed by any number of PROFF commands and/or text which define the action that the macro will subsequently produce. Macros may refer to other macros. \set ENM ".en" \comm ENM End macro is the last line in the command definition. You must put in this command to finish a currently defined macro. ".en" command should not be re-defined as a macro. \in -5 \sp The example below defines macros ".note" and ".endnote", similar to the RUNOFF commands of the same name. \in +5 \nap \nf \need 20 \sp | |.define note |.sp |.ce |NOTE |.sp |.fi |.in +5 |.rm -5 |.en | |.define endnote |.sp |.nf |.in -5 |.rm +5 |.en | \in -5 \ap \fi A macro is used like any other PROFF command, control character followed immediately by the name of the macro. For example, the above macros may be used as follows: \in +5 \nap \need 9 \nf \sp | |.note |textextextextextextextextextext | . | . | . |.endnote | \in -5 \sp \fi The following note is generated by the same macros described previously. \cc . .nap .note Flap's Law: Any inanimate object, regardless of its position or configuration, may be expected to perform at any time in a totally unexpected manner for reasons that are either entirely obscure or else completely mysterious. .endnote .fi .cc \ \ap Special symbols may be used within a macro definition. These symbols represent the parameters passed to a macro, delimited by blanks or commas. These symbols are _$0 for macro name, _$1 for the first parameter, _$2 for the second parameter and so on, up to _$9 for the ninth parameter. Currently, macro parameters may only contain alphanumerics, no string parameters are possible. The previous macro "note" may now be defined as follows: \in +5 \nap \nf \need 20 \sp | |.define note |.sp |.ce |_$2 _$3 _$4 _$5 _$6 _$7 _$8 _$9 |.nr m _$1 |.sp |.fi |.in +_$1 |.rm -_$1 |.en | |.define endnote |.sp |.nf |.in -_@nm |.rm +_@nm |.en | \in -5 \ap \fi In this version of the "note" and "endnote" macros, the first parameter (_$1) is used to pass the value for indentation and right margin adjustment. All the rest of the macro parameters (_$2 - _$9) are used as the title of the note. The indent value passed as the first parameter is also saved in the number register "m" to communicate it to the "endnote" macro, such that when the endnote macro is called, both indent and right margin values are adjusted back to normal. It is possible and may be more useful to use ".save" and ".restore" commands to accomplish the same task, especially if the macro alters the current formatting context drastically. The ".note" and ".endnote" macros may be called as follows: \in +5 \nap \need 9 \nf \sp | |.note 5 Asimov's Law of Robotics |textextextextextextextextextext | . | . | . |.endnote | \in -5 \fi \ap In this usage, the indent value will be adjusted by +5, right margin will be adjusted by -5, and the title "Asimov's Law of Robotics" will appear centered above the note. \cchar . .bp .cl .sect 0 4.0 Executing PROFF The PROFF program may be invoked with a series of optional parameters and filenames on the command line. The command synopsis is: PROFF [+n] [-n] [-v] [-s] [-pon] [-ifile] input [output] The square brackets indicate an optional parameter. Interpretation of the parameters is as follows: .nap .in +10 .define opt .need 5 .sp .ti -5 .bd $1 .br .en .opt +n Start the printing of the document at the first page with number n. .opt -n Stop printing at the first page numbered higher than n. .opt -v Verbose mode. PROFF indicates the source files being included into document, and produces a summary of the number of textlines read in, the number of lines and actual pages generated. A memory usage summary of internal storage for macros, stacks and tables is also displayed. .opt -s Stop before each page, including the first one to allow paper adjustment. A prompt is given just before the first page. For each page thereafter, the terminal bell is rung to indicate that another sheet of paper is needed. .opt -pon Sets the page offset to n. This is equivalent to ".po" command within the document. It is recommended that -pon option be used instead of embedding the offset value within the document. .opt -ifile Includes the given file to the formatted document. This is equivalent to a ".include file" command within the document. This option may be repeated more than once, -ifile1 -ifile2 etc. .opt input Specifies the input file to be formatted. PROFF does not impose any file extension. The recommended extension is ".PRF". .opt output Specifies the output file for the formatted document. If this is omitted, output is directed to the user's terminal. .in -10 Following are some examples of PROFF command lines: .ti +5 A>PROFF -v proffman.prf Format this document (proffman.prf) in verbose mode, and output the formatted document to the terminal. .ti +5 A>PROFF +5 -imacros.pma proffman.prf Format this document, include the external file MACROS.PMA, skip the first four pages and output the formatted document to the terminal. .ti +5 A>PROFF -po10 proffman.prf proff.man Format this document, shift the entire document by 10 spaces to right and output to a file called proff.man. .bp .cl .sect 0 5.0 Tips on using PROFF .ap .sect 1 5.1 Care and Feeding of Memory PROFF uses a dynamic memory allocation scheme for some of its operations. These are macro definitions, contents lines, variables and save context operation. Running PROFF under microcomputers with limited memory resources (64k or less) require some care in using these commands: .list 3 .item a) Do not declare macros that are not needed within the document. .item b) Do not use comments within macros. Due to delayed evaluation, comments will also be stored as a part of the macro definition. .item c) Where possible, avoid using too much text within macros. It is just as easy to pass the information during the macro call. .item d) Use only the shortest form of commands within macros. .item e) Be brief in contents line text. .item f) Use short variable names as long as it is not so cryptic as to be confusing. .item g) Avoid unnecessary blanks within the variable definitions. .item h) Avoid too many context saves without a corresponding restore. The restore operation reclaims the memory used for a save. .nolist Even if the formatter is used with a system of large memory resources, some of the precautions above are applicable. (Utz's 4th law of Computer Programming: Any given program will eventually expand to fill all the available memory.) Using the -v option under memory-restricted systems may be useful in determining the memory usage. .sect 1 5.2 Formatting without fuss PROFF, using its default settings, may provide reasonably formatted output in many situations. As an example, examine the document PROFF.TUT. This document does not use ANY formatting commands. All formatting is done with the default settings. .sect 1 5.3 Variables within macros Variable expansions may be performed within the macros. Typically, one of the parameters of the macro is assumed to be a variable, which is expanded only after the macro is used. Thus: .in +5 .nf | |.define xx |.ce |_$_$1 |.cl _$_$1 |.en | .in -5 .fi The macro xx assumes the first parameter to be a variable, which is centered on the page, and also entered in the table of contents. Note the usage of "_$_$1". The lines within a macro are scanned from right to left for parameter expansion. Thus, "_$1" is expanded first, resulting in "_$". This is later expanded as a variable. .bp .cl .sect 0 6.0 Example macros .nf .in +5 .cc \ .! .! macros to create a point-form lists. .! note the use of number registers within .! the macros. .!------------ .define list .nr a _$1 .in _$1 .en .!------------ .define item .sp .ti -_@na _$1 .en .!------------ .define nolist .in -_@na .sp .en .!------------ \in -5 \fi The "list" macro is used to generate point-form lists. The first parameter is an indent value, size of point-str + 1. A typical usage may be as follows: \need 16 \in +5 \nf | |Project work involves: |.sp |.list 3 { size-of-point-str + 1 } |.item a) { "a)" is the point-str } |choosing a topic |.item b) |defining the topic |.item c) |research |.item d) |organizing the notes |{etc.} |.nolist { readjusts the indent } | \in -5 The above usage will produce the following: \need 12 \in +5 | |Project work involves: | |a) choosing a topic | |b) defining the topic | |c) research | |d) organizing the notes | \in -5 \fi The point-form recommendations under section 5.1 (Care and Feeding of Memory) were generated with the same set of macros described above. \cc . .bp .cl .sect 0 7.0 Acknowledgements This document was edited by Terry Lim and Steven Tress. The format of the document is largely based on The Freshwater Institute RUNOFF User's Guide. The Quotes for the various formatting examples are from THE QUOTABLE NOTHING BOOK and from 1001 LOGICAL LAWS, ACCURATE AXIOMS, PROFOUND PRINCIPLES, TRUSTY TRUISMS, HOMEY HOMILIES, COLORFUL COROLLARIES, QUOTABLE QUOTES, AND RAMBUNCTIOUS RUMINATIONS FOR ALL WALKS OF LIFE, by Peers, Bennet and Booth, Fawcett Columbine Books, New York. .bp .cl .sect 0 Appendix A .he /1.0/Appendix A/#/ .cc \ \nf \nap \ce Summary of Commands ---------------------------------------------------------- $FILL default: initial: yes break: yes begin filling output lines ---------------------------------------------------------- $NOFILL default: initial: no break: yes stop filling ---------------------------------------------------------- $JUST default: initial: yes break: yes begin justifying filled lines ---------------------------------------------------------- $NOJUST default: initial: no break: yes stop justifying ---------------------------------------------------------- $BREAK default: initial: break: yes cause a break and output current line ---------------------------------------------------------- $INDENT default: 0 inital: 0 break: yes set left margin to column n+1 ---------------------------------------------------------- $TINDENT default: 0 initial: break: yes temporarily indent next output n spaces ---------------------------------------------------------- $SPACETO default: 0 initial: break: yes space to line +n from top space to line -n from bottom ---------------------------------------------------------- $SPACE default: 1 initial: break: yes space n lines except at top of page ---------------------------------------------------------- $CENTER default: 1 initial break: yes center next n lines center until turned off ---------------------------------------------------------- $UNDLINE default: 1 initial break: no underline next n lines underline until turned off ---------------------------------------------------------- \bp ---------------------------------------------------------- $CUNDLINE default: words initial: words break: no set mode for underline - words or all ---------------------------------------------------------- $BOLD default: 1 initial: break: no boldface (overstrike) next n lines boldface until turned off ---------------------------------------------------------- $DBO default: initial: no break: no disable bolding ---------------------------------------------------------- $EBO default: initial: yes break: no enable bolding ---------------------------------------------------------- $LS default: 1 initial: 1 break: no set line spacing to n ---------------------------------------------------------- $BP default: +1 initial: 1 break: yes begin a new page and number it n ---------------------------------------------------------- $PN default: initial: arabic break: no set page numbering to arabic or roman ---------------------------------------------------------- $NPA default: initial: no break: yes disable paging ---------------------------------------------------------- $PA default: initial: yes break: yes enable paging ---------------------------------------------------------- $NE default: 0 initial: break: yes/no need n lines. Break and generate a new page if not available ---------------------------------------------------------- $HE default: null initial: null break: no set header to text (/left/center/right/) ---------------------------------------------------------- $FO default: null initial: null break: no set footer to text (/lef/center/right/) ---------------------------------------------------------- \bp ---------------------------------------------------------- $OHE default: null initial: null break: no set header on odd pages to text ---------------------------------------------------------- $EHE default: null initial: null break: no set header on even pages to text ---------------------------------------------------------- $OFO default: null initial: null break: no set footer on odd pages to text ---------------------------------------------------------- $EFO default: null initial: null break: no set footer on odd pages to text ---------------------------------------------------------- $PO default: 0 initial: 0 break: yes set page offset to n spaces ---------------------------------------------------------- $RM default: 65 initial: 65 break: no set right margin to column n ---------------------------------------------------------- $PL default: 66 initial: 66 break: no set page length to n lines ---------------------------------------------------------- $M1 default: 3 initial: 3 break: no lines between top of page and header ---------------------------------------------------------- $M2 default: 2 initial: 2 break: no lines between header and text ---------------------------------------------------------- $M3 default: 2 initial: 2 break: no lines between text and footer ---------------------------------------------------------- $M4 default: 3 initial: 3 break: no lines between footer and bottom ---------------------------------------------------------- $CL default: initial: break: yes enter text into table of contents at level n ---------------------------------------------------------- \bp ---------------------------------------------------------- $PC default: 3 initial: 3 break: yes print table of contents, indent each level n spaces ---------------------------------------------------------- $VSET default: initial: break: no set variable to text ---------------------------------------------------------- $VGET default: initial: break: no set variable interactively, using text as prompt ---------------------------------------------------------- $VRG default: 0 initial: 0 break: no set number register (a-z) to n ---------------------------------------------------------- $CCHAR default: "." initial: "." break: no set command control character to char ---------------------------------------------------------- $ECHAR default: "__" initial: "__" break: no set universal escape character to char ---------------------------------------------------------- $SOU default: initial: input break: no switch input to file ---------------------------------------------------------- $SAVE default: initial: break: yes save the current formatter context on context stack ---------------------------------------------------------- $RST default: initial: break: yes restore the formatter context from context stack ---------------------------------------------------------- $LEX default: initial: break: no rename a command ---------------------------------------------------------- $APR default: initial: no break: no enable auto-paragraphing ---------------------------------------------------------- \bp ---------------------------------------------------------- $NAP default: initial: yes break: no disable auto-paragraphing ---------------------------------------------------------- $WRT default: initial: break: no write a special string to output. line counter does not change ---------------------------------------------------------- $DEF default: initial: break: no define a macro command - ends at ".en" ---------------------------------------------------------- $ENM default: initial: break: no end the macro definition ---------------------------------------------------------- \cc . .bp 1 .pn roman .he //// .fo //- # -// .ce on Table Of Contents PROFF 1.0 .ce off .pc